home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3 / SCSL / intro_cblas.z / intro_cblas
Encoding:
Text File  |  2002-10-03  |  19.7 KB  |  397 lines

  1.  
  2.  
  3.  
  4. IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS((((3333SSSS))))                                                IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS((((3333SSSS))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS - Introduction to the C interface to Fortran 77 Basic Linear
  10.      Algebra Subprograms (legacy BLAS)
  11.  
  12. IIIIMMMMPPPPLLLLEEEEMMMMEEEENNNNTTTTAAAATTTTIIIIOOOONNNN
  13.      See individual man pages for operating system and hardware availability.
  14.  
  15. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  16.      The SCSL Scientific Library provides two C/C++ interfaces to the Fortran
  17.      77 Basic Linear Algebra Subprograms (legacy BLAS). This man page
  18.      describes a C interface proposed by the Basic Linear Algebra Subprograms
  19.      Technical (BLAST) Forum as well as several SCSL extensions to that
  20.      standard.  An alternative C/C++ interface, similar to that implemented
  21.      for the SCSL signal processing library, is described in individual BLAS
  22.      man pages.
  23.  
  24.    HHHHeeeeaaaaddddeeeerrrr FFFFiiiilllleeeessss
  25.      To use the CBLAS interface, a program must include the header file
  26.      ccccbbbbllllaaaassss....hhhh:
  27.  
  28.           #include <cblas.h>
  29.  
  30.  
  31.      For compatibility with SCSL releases prior to version 1.3, the
  32.      ssssccccssssllll____ccccbbbbllllaaaassss....hhhh header file may be used instead of ccccbbbbllllaaaassss....hhhh.
  33.  
  34.    NNNNaaaammmmiiiinnnngggg CCCCoooonnnnvvvveeeennnnttttiiiioooonnnnssss
  35.      Names of the CBLAS routines are obtained from their legacy BLAS
  36.      counterparts by prefixing the name with ccccbbbbllllaaaassss____ and converting to lower
  37.      case.  For example, the routine DDDDGGGGEEEEMMMMMMMM becomes ccccbbbbllllaaaassss____ddddggggeeeemmmmmmmm.
  38.  
  39.    CCCChhhhaaaarrrraaaacccctttteeeerrrr AAAArrrrgggguuuummmmeeeennnnttttssss
  40.      Arguments which were characters in the Fortran 77 interface are handled
  41.      by enumerated types in the CBLAS interface, as shown in the following
  42.      table.
  43.  
  44.              Fortran interface                    CBLAS interface
  45.  
  46.        Character Argument    Value         Enumerated type        Value
  47.  
  48.            SIDE               'L'          CBLAS_SIDE           CblasLeft
  49.                               'R'                               CblasRight
  50.  
  51.            UPLO               'U'          CBLAS_UPLO           CblasUpper
  52.                               'L'                               CblasLower
  53.  
  54.            DIAG               'N'          CBLAS_DIAG           CblasNonUnit
  55.                               'U'                               CblasUnit
  56.            TRANSPOSE          'N'          CBLAS_TRANSPOSE      CblasNoTrans
  57.                               'T'                               CblasTrans
  58.                               'C'                               CblasConjTrans
  59.  
  60.  
  61.  
  62.  
  63.                                                                         PPPPaaaaggggeeee 1111
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70. IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS((((3333SSSS))))                                                IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS((((3333SSSS))))
  71.  
  72.  
  73.  
  74.                                            CBLAS_ORDER          CblasRowMajor
  75.                                                                 CblasColMajor
  76.  
  77.  
  78.      The last enumerated type listed above, CCCCBBBBLLLLAAAASSSS____OOOORRRRDDDDEEEERRRR, has no Fortran
  79.      counterpart.  It is used as an additional argument to all routines
  80.      involving two-dimensional arrays, as discussed in the following section.
  81.  
  82.    AAAArrrrrrrraaaayyyy AAAArrrrgggguuuummmmeeeennnnttttssss
  83.      Array elements are required to be contiguous in memory.  All legacy BLAS
  84.      routines which take one or more two-dimensional arrays as arguments have
  85.      an extra argument in the CBLAS interface.  First in the argument list,
  86.      this parameter is of the enumerated type:
  87.  
  88.           enum CBLAS_ORDER {CblasRowMajor=101, CblasColMajor=102};
  89.  
  90.  
  91.      CCCCbbbbllllaaaassssRRRRoooowwwwMMMMaaaajjjjoooorrrr indicates that elements within a row of the array(s) are
  92.      contiguous in memory while elements within array columns are offset by a
  93.      constant stride.  The stride parameter is equivalent to the leading
  94.      dimension (LDA) in the Fortran 77 interface.
  95.  
  96.      Similarly, CCCCbbbbllllaaaassssCCCCoooollllMMMMaaaajjjjoooorrrr indicates that elements within a column of the
  97.      array(s) are contiguous in memory while elements within array rows are
  98.      offset by a constant stride.
  99.  
  100.      The CCCCBBBBLLLLAAAASSSS____OOOORRRRDDDDEEEERRRR parameter applies to all array operands in a routine.
  101.  
  102.    CCCCoooommmmpppplllleeeexxxx DDDDaaaattttaaaa TTTTyyyyppppeeeessss
  103.      The BLAST standard does not define a complex data type for use in
  104.      routines having complex arguments.  Instead, all complex scalars and
  105.      arrays are prototyped as vvvvooooiiiidddd ****.  This has the advantage of allowing the
  106.      use of any complex data structure without warnings from the compiler,
  107.      provided that the structure meets the specifications described below.
  108.      The disadvantage, however, is that the compiler will not catch type
  109.      mismatches.
  110.  
  111.      Any C/C++ complex data type used in conjunction with the CBLAS interface
  112.      must satisfy the following requirements:
  113.  
  114.      1.   The real and imaginary components must be contiguous in memory.
  115.  
  116.      2.   Sequential array elements must also be contiguous in memory.
  117.  
  118.      As an extension to the BLAST standard, SCSL provides support for stronger
  119.      type checking for complex arguments.  To enable this, define
  120.      SSSSCCCCSSSSLLLL____NNNNOOOO____VVVVOOOOIIIIDDDD____AAAARRRRGGGGSSSS before including the CBLAS header file (for example, at
  121.      compile time with ----DDDDSSSSCCCCSSSSLLLL____NNNNOOOO____VVVVOOOOIIIIDDDD____AAAARRRRGGGGSSSS as an argument or with an explicit
  122.      ####ddddeeeeffffiiiinnnneeee SSSSCCCCSSSSLLLL____NNNNOOOO____VVVVOOOOIIIIDDDD____AAAARRRRGGGGSSSS in the source code).  With this definition, the
  123.      default behavior is as follows:
  124.  
  125.  
  126.  
  127.  
  128.  
  129.                                                                         PPPPaaaaggggeeee 2222
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136. IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS((((3333SSSS))))                                                IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS((((3333SSSS))))
  137.  
  138.  
  139.  
  140.      *   For C++ code in which the complex standard template library (STL) is
  141.          used, single precision complex arguments are prototyped aaaassss
  142.          ccccoooommmmpppplllleeeexxxx<<<<ffffllllooooaaaatttt>>>> **** and double precision complex arguments are
  143.          prototyped as ccccoooommmmpppplllleeeexxxx<<<<ddddoooouuuubbbblllleeee>>>> ****.
  144.  
  145.      *   Otherwise, single precision complex arguments are prototyped as
  146.          ssssccccssssllll____ccccoooommmmpppplllleeeexxxx **** and double precision complex arguments are prototyped
  147.          as ssssccccssssllll____zzzzoooommmmpppplllleeeexxxx **** for both C and C++.  The SCSL complex types are
  148.          defined as follows:
  149.  
  150.               typedef struct { float re; float im; } scsl_complex;
  151.               typedef struct { double re; double im; } scsl_zomplex;
  152.  
  153.  
  154.      Strong type checking also can be enabled in programs employing their own
  155.      (non-SCSL, non-C++ STL) complex types.  To do this, define
  156.      SSSSCCCCSSSSLLLL____UUUUSSSSEEEERRRR____CCCCOOOOMMMMPPPPLLLLEEEEXXXX____TTTT====_m_y__c_o_m_p_l_e_x and SSSSCCCCSSSSLLLL____UUUUSSSSEEEERRRR____CCCCOOOOMMMMPPPPLLLLEEEEXXXX____TTTT====_m_y__z_o_m_p_l_e_x, where
  157.      _m_y__c_o_m_p_l_e_x and _m_y__z_o_m_p_l_e_x are the names of user-defined complex types.
  158.      These complex types, as well as SSSSCCCCSSSSLLLL____NNNNOOOO____VVVVOOOOIIIIDDDD____AAAARRRRGGGGSSSS, must be defined before
  159.      including the CBLAS header file (see Example 5 later in this man page).
  160.  
  161.    RRRRoooouuuuttttiiiinnnneeeessss tttthhhhaaaatttt RRRReeeettttuuuurrrrnnnn IIIInnnnddddiiiicccceeeessss
  162.      Following the array indexing convention of Fortran 77, the legacy BLAS
  163.      return indices in the range 1 <= _i <= _n, where _n is the number of entries
  164.      and _i is the index. This allows the returned indices to be used to index
  165.      standard arrays directly.  The C interface therefore returns indices in
  166.      the range 0 <= _i < _n for the same reason. Functions that return an index
  167.      are IIII[[[[SSSSDDDDCCCCZZZZ]]]]AAAAMMMMAAAAXXXX, IIII[[[[SSSSDDDDCCCCZZZZ]]]]AAAAMMMMIIIINNNN, IIII[[[[SSSSDDDD]]]]MMMMAAAAXXXX and IIII[[[[SSSSDDDD]]]]MMMMIIIINNNN, which are declared
  168.      to be of type CCCCBBBBLLLLAAAASSSS____IIIINNNNDDDDEEEEXXXX.
  169.  
  170.    RRRRoooouuuuttttiiiinnnneeeessss tttthhhhaaaatttt RRRReeeettttuuuurrrrnnnn CCCCoooommmmpppplllleeeexxxx VVVVaaaalllluuuueeeessss
  171.      For each routine returning a complex value ([[[[CCCCZZZZ]]]]DDDDOOOOTTTTCCCC, [[[[CCCCZZZZ]]]]DDDDOOOOTTTTUUUU, [[[[CCCCZZZZ]]]]SSSSUUUUMMMM)
  172.      the BLAST standard defines a subroutine that returns a pointer to the
  173.      result as the last parameter of the argument list.  All other arguments
  174.      are otherwise the same.  The name of the subroutine is obtained by
  175.      appending ____ssssuuuubbbb to the CCCCBBBBLLLLAAAASSSS name; for example, CCCCDDDDOOOOTTTTCCCC becomes
  176.      ccccbbbbllllaaaassss____ccccddddoooottttcccc____ssssuuuubbbb.
  177.  
  178.      In the SCSL implementation complex functions can be called directly
  179.      provided that SSSSCCCCSSSSLLLL____NNNNOOOO____VVVVOOOOIIIIDDDD____AAAARRRRGGGGSSSS is defined, in which case the function
  180.      returns a structure of the appropriate type.  The function naming and
  181.      calling conventions are the same as those for real functions (i.e., ____ssssuuuubbbb
  182.      is not appended to the name, and no extra parameter is added).
  183.  
  184.    OOOOtttthhhheeeerrrr IIIInnnntttteeeerrrrffffaaaacccceeee NNNNooootttteeeessss
  185.      Input-only arguments are declared with the ccccoooonnnnsssstttt modifier.
  186.  
  187.      Non-complex scalar input arguments are passed by value.  This allows the
  188.      user to put in constants when desired.
  189.  
  190.  
  191.  
  192.  
  193.  
  194.  
  195.                                                                         PPPPaaaaggggeeee 3333
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202. IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS((((3333SSSS))))                                                IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS((((3333SSSS))))
  203.  
  204.  
  205.  
  206.      Array arguments are passed by address.
  207.  
  208.      Output scalar arguments are passed by address.
  209.  
  210.      The CBLAS routines can be loaded at compile time using either the ----llllssssccccssss
  211.      or the ----llllssssccccssss____mmmmpppp option.  The ----llllssssccccssss____mmmmpppp option directs the linker to use
  212.      the multi-processor version of SCSL.
  213.  
  214.      When linking to SCSL with ----llllssssccccssss or ----llllssssccccssss____mmmmpppp, the default integer size is
  215.      4 bytes (32 bits). Another version of the library is available in which
  216.      integers are 8 bytes (64 bits).  This version allows the user access to
  217.      larger memory sizes and helps when porting legacy Cray codes. It can be
  218.      loaded by using the ----llllssssccccssss____iiii8888 option or the ----llllssssccccssss____iiii8888____mmmmpppp option. A program
  219.      may use only one of the two versions; 4-byte integer and 8-byte integer
  220.      library calls cannot be mixed.
  221.  
  222.      When using the 8-byte integer version, variables of type iiiinnnntttt become lllloooonnnngggg
  223.      lllloooonnnngggg and the ccccbbbbllllaaaassss____iiii8888....hhhh header file should be included.
  224.  
  225. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  226.      Example 1:  Multiply a real 10 x 20 matrix by a real 20 x 30 matrix.  Use
  227.      the "natural" form for C arrays.
  228.  
  229.      #include <cblas.h>
  230.      float a[10][20], b[20][30], c[10][30];
  231.      cblas_sgemm(CblasRowMajor, CblasNoTrans, CblasNoTrans, 10, 30,
  232.                  20, 1.0f, a, 20, b, 30, 0.0f, c, 30);
  233.  
  234.  
  235.      Example 2:  Multiply a real 10 x 20 matrix by a real 20 x 30 matrix.  Use
  236.      8-byte integers and column-major array ordering.
  237.  
  238.      #include <cblas_i8.h>
  239.      float a[20][10], b[30][20], c[30][10];
  240.      cblas_sgemm(CblasColMajor, CblasNoTrans, CblasNoTrans, 10LL, 30LL,
  241.                  20LL, 1.0f, a, 10LL, b, 20LL, c, 10LL);
  242.  
  243.  
  244.      Examples 1 and 2 will result in a warning message when compiled as C code
  245.      and an error message when compiled with as C++ code because aaaa, bbbb, and cccc
  246.      are prototyped as ffffllllooooaaaatttt ****.  There are several ways to avoid these
  247.      problems, perhaps the easiest of which is to make explicit casts when
  248.      calling the CBLAS routine:
  249.  
  250.      cblas_sgemm(CblasRowMajor, CblasNoTrans, CblasNoTrans, 10, 30,
  251.                  20, 1.0f, (float *) a, 20, (float *) b, 30, 0.0f,
  252.                  (float *) c, 30);
  253.  
  254.  
  255.      Another solution is to declare aaaa, bbbb, and cccc as the following:
  256.  
  257.           float a[10*20], b[20*30], c[10*30];
  258.  
  259.  
  260.  
  261.                                                                         PPPPaaaaggggeeee 4444
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268. IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS((((3333SSSS))))                                                IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS((((3333SSSS))))
  269.  
  270.  
  271.  
  272.      Of course, in this case two-dimensional indexing is no longer possible.
  273.      For example, if we assume that bbbb has 20 rows and 30 columns, then the _ith
  274.      element of the _jth column of bbbb must be referenced as bbbb[[[[iiii****33330000++++jjjj]]]] rather
  275.      than bbbb[[[[iiii]]]][[[[jjjj]]]].
  276.  
  277.      Note that the following is acceptable:
  278.  
  279.           #include <stdlib.h>
  280.           float *a, *b, *c;
  281.           a = (float *) malloc(10 * 20 * sizeof(float));
  282.           b = (float *) malloc(20 * 30 * sizeof(float));
  283.           c = (float *) malloc(10 * 30 * sizeof(float));
  284.  
  285.  
  286.      The following gives unpredictable results since the array elements are
  287.      not contiguous in memory.
  288.  
  289.           #include <stdlib.h>
  290.           float *a[10], *b[20], *c[10];
  291.           int i;
  292.           for (i = 0; i < 10; i++) {
  293.               a[i] = (float *) malloc(20 * sizeof(float));
  294.               b[2*i] = (float *) malloc(30 * sizeof(float));
  295.               b[2*i+1] = (float *) malloc(30 * sizeof(float));
  296.               c[i] = (float *) malloc(30 * sizeof(float));
  297.           }
  298.  
  299.  
  300.      Example 3:  Multiply a complex 10 x 20 matrix by a complex 20 x 30
  301.      matrix.  Use the C++ STL and row-major ordering.
  302.  
  303.      #include <complex.h>
  304.      #include <cblas.h>
  305.      complex<float> a[10][20], b[20][30], c[10][30];
  306.      complex<float> alpha(1.0,0.0);
  307.      complex<float> beta(0.0,0.0);
  308.      cblas_cgemm(CblasRowMajor, CblasNoTrans, CblasNoTrans, 10, 30,
  309.                  20, &alpha, a, 20, b, 30, &beta, c, 30);
  310.  
  311.  
  312.      Because complex arguments are prototyped as vvvvooooiiiidddd **** by default, the
  313.      multidimensional array declarations in the example above will not result
  314.      in any type mismatches at compile time.  In the following strong type
  315.      checking examples the complex matrices are stored in explicitly one-
  316.      dimensional form.
  317.  
  318.      Example 4:  Multiply a complex 10 x 20 matrix by a complex 20 x 30
  319.      matrix.  Use the SCSL complex type and strong type checking.
  320.  
  321.      #define SCSL_NO_VOID_ARGS
  322.      #include <cblas.h>
  323.      scsl_complex a[10*20], b[20*30], c[10*30];
  324.  
  325.  
  326.  
  327.                                                                         PPPPaaaaggggeeee 5555
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334. IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS((((3333SSSS))))                                                IIIINNNNTTTTRRRROOOO____CCCCBBBBLLLLAAAASSSS((((3333SSSS))))
  335.  
  336.  
  337.  
  338.      scsl_complex alpha = {1.0, 0.0};
  339.      scsl_complex beta = {0.0, 0.0};
  340.      cblas_cgemm(CblasRowMajor, CblasNoTrans, CblasNoTrans, 10, 30,
  341.                  20, &alpha, a, 20, b, 30, &beta, c, 30);
  342.  
  343.  
  344.      Example 5:  Multiply a complex 10 x 20 matrix by a complex 20 x 30
  345.      matrix.  Define your own complex type.
  346.  
  347.      #define SCSL_NO_VOID_ARGS
  348.      #define SCSL_USER_COMPLEX_T CBLAS_COMPLEX
  349.      #define SCSL_USER_COMPLEX_T CBLAS_ZOMPLEX
  350.      typedef struct { float real; float imag; } CBLAS_COMPLEX;
  351.      typedef struct { double real; double imag; } CBLAS_ZOMPLEX;
  352.      #include <cblas.h>
  353.      CBLAS_COMPLEX a[10*20], b[20*30], c[10*30];
  354.      CBLAS_COMPLEX alpha = {1.0, 0.0};
  355.      CBLAS_COMPLEX beta = {0.0, 0.0};
  356.      cblas_cgemm(CblasRowMajor, CblasNoTrans, CblasNoTrans, 10, 30,
  357.                  20, &alpha, a, 20, b, 30, &beta, c, 30);
  358.  
  359.  
  360.  
  361. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  362.      IIIINNNNTTTTRRRROOOO____SSSSCCCCSSSSLLLL(3S), IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS1111(3S), IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS2222(3S), IIIINNNNTTTTRRRROOOO____BBBBLLLLAAAASSSS3333((((3333SSSS)))),
  363.      IIIINNNNTTTTRRRROOOO____LLLLAAAAPPPPAAAACCCCKKKK((((3333SSSS))))
  364.  
  365.      The working document for the Basic Linear Algebra Subprograms (BLAS)
  366.      standard from the Basic Linear Algebra Subprograms Technical (BLAST)
  367.      Forum is available at
  368.      hhhhttttttttpppp::::////////wwwwwwwwwwww....nnnneeeettttlllliiiibbbb....oooorrrrgggg////ccccggggiiii----bbbbiiiinnnn////cccchhhheeeecccckkkkoooouuuutttt////bbbbllllaaaasssstttt////bbbbllllaaaasssstttt....ppppllll.
  369.  
  370.  
  371.  
  372.  
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.                                                                         PPPPaaaaggggeeee 6666
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.